JSON Event

About the JSON Event

Have you ever wanted a request made on your website to trigger a ticket in Qualtrics? Have you ever wanted to create a seamless integration between Qualtrics and your own internal system? Have you ever wanted to trigger a task in the Workflows tab, but with an event that happens outside of Qualtrics?

JSON events allow external software to start workflows via HTTP request. Instead of waiting for an event in Qualtrics to trigger further action in the platform, you can simply configure a JSON event to receive requests from a third party.

Limitations

The JSON event is not compatible with the following set-ups and configurations:

• Anything that is not HTTP (e.g., message queue, SMS).
• Outbound HTTP calls.
• Process XML (the XML request body will be ignored).
• Process anything other than JSON.
• Authenticate any way other than an X-API-TOKEN header or our modified HTTP basic auth.
  Qtip: OAuth and other forms of authentication are incompatible with JSON events.
• Any JSON parsing that cannot be satisfied by using JSONPath queries on the JSON body.
• Calls exceeding the API rate limit of 3,000 per minute.
• Payloads exceeding 100 KB.

Types of Auth Supported

Token-Based Auth / Header Auth

You can authenticate by passing your API token through the header of the request as X-API-TOKEN.

curl -X POST -H 'X-API-TOKEN: yourapitokenhere' -H 'Content-Type: application/json' -d '{

    "surveyId": "SV_012345678912345",

    "format": "csv"

}' 'https://yourdatacenterid.qualtrics.com/API/v3/responseexports'

HTTP Basic Auth

Basic Auth is usually a Base64 encoded version of username:password. However, for improved security, Qualtrics uses a Base64 encoded string of username:x-api-token.

To use Basic Auth, you must set headers on the HTTP request. The specific header is Authorization.

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 Basic ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

Setting Up a JSON Event

1. First, you will need to create a workflow. Go to the stand-alone Workflows page.
   
   Qtip: You can also use JSON events in the Workflows tab in a project. We only recommend adding a workflow to a specific project if they’re explicitly related. (For example, you are distributing that project with the JSON event.)
2. Make sure you’re in the Your workflows tab.
3. Click Create a workflow.
4. Select Started when an event is received.
5. Select the JSON event.
   
6. If you’d like, specify a Trigger summary, which should describe the purpose of the JSON event.
7. You will be given a URL. Use this to invoke your new workflow from outside Qualtrics, using Postman, your own internal system, or other similar applications. To copy it, click Copy URL.
8. By default, JSON events require authentication. If you want to allow unauthenticated requests, you can disable Require authentication by Qualtrics.
9. Now, you can define the event data. This will capture data from the inbound request. To start, click Advanced settings.
   
   Qtip: For information about the Test section, see Capturing Events below.
10. On the box on the left, give the JSON field name. On the box on the right, give the location within the event data (HTTP request body).
    Qtip: The locations must be in JSONPath format! See the table below for a quick guide to JSONPath Syntax.
11. To add another field, click Add a JSON field.
12. If you’d like to add a QUERY parameter, add them in the QUERY Parameters section. For more on what these parameters are and how they work in API, see our API Documentation on Parameters.
    Warning: It is not advisable to pass personally identifiable data through QUERY parameters. Any personally identifiable information or sensitive data should be passed through the POST body whenever possible, as POST is more secure. Please contact Qualtrics Support if you have questions or concerns.
13. To remove a field, click the minus sign ( – ).
14. To save your changes, click Save.
15. Now you can add conditions and a task to your workflow by clicking the plus sign ( + ). Conditions determine when a workflow runs, while tasks are the result of the workflow. See the Workflows Overview for more information.
    

Capturing Events

When you are creating an external API event, you may need to parse data from the post body. However, it can be difficult at times to parse this data. If you want to figure out what your external API is sending, follow these steps.

1. Click on your JSON event.
   
2. By default, the Capture JSON fields from the test results so they can be used as piped-text in other tasks in this workflow option will be enabled. This option makes it so that fields parsed into the body of the payload will be automatically available as piped text when you add your workflow tasks.
   
3. Click Run a new test.
4. You will see a message that Qualtrics is waiting to receive the event from your external system. Fire your external API.
   Qtip: To cancel this test, click Cancel test.
5. If the test was successful, you will see the message Successfully connected to the server. The payload will be parsed and added to the window.
6. If desired, click Run a new test to run another test. You will need to run your next API call after this option is clicked.
7. Click Save.

JSONPath Syntax

The table below gives some of the basics of JSONPath Syntax. Note that these are not established by Qualtrics, but are standards used with JSON.

JSONPath Syntax Example

In this example, we will show you how, given a JSON object, the JSONPath table can be used.

This is our JSON object:

{
"eventDescription": "Monthly Revenue",
"stores": [
{
"name": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "description": "Anvil" }
},
{
"name": "The Banana Stand",
"total": 250000,
"topItem":

{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":

{ "price": "15", "description": "Pepperoni" }
}
]
}

Now, we should add the return values we see in the JSONPath table to make it more clear.

$ -> Acme Store
@ -> [
{
"name": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "description": "Anvil" }
}
]
. -> Monthly Revenue
.. -> 50

-> ["Acme Store", "The Banana Stand", "Pizza Planet"]
[] -> Acme Store
[,] -> [
Unknown macro: { "name"}
,

Unknown macro: { "name"}
]

**Change [start:end:step]'s Example to be "$.stores[1:3:1]"
[start:end:step] -> [
{
"name": "The Banana Stand",
"total": 250000,
"topItem":

{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":

{ "price": "15", "description": "Pepperoni" }
}
]

?() -> [{
"name": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "description": "Anvil" }
}]

() -> [
{
"name": "Pizza Planet",
"total": 80000,
"topItem":

{ "price": "15", "description": "Pepperoni" }
}
]

Example API in Node Javascript

The example below is a basic template you can follow when formatting your Event Data.

var request = require('request-promise');
var surveyId = "SV_XXXXXXXXXXXX";
var triggerId = "OC_XXXXXXXXX";
var brandId = "YOUR_BRAND_ID";
var userId = "UR_XXXXXXXXXXXXXXX";
var datacenter = "xx1";
var apiToken = "YOUR_QUALTRICS_API_TOKEN";

var url = "https://" + datacenter + ".qualtrics.com/inbound-event/v1/event/JSON/triggers" +
     "?contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
var payload = {
    "text": "This is some text",
    "object": {
        "number": 4
    },
    "array": ["a", "b", "c", "d"]
};

var options = {
    url: url,
    json: true,
    body: payload,
    headers: {
        "Content-Type": "application/json", // REQUIRED!!!
        "X-API-TOKEN": apiToken
    }
};

request.post(options).then(function (ret) {
    console.log("success:", url, payload);
}).catch(function (err) {
    console.log("error: ", url);
    console.log(err);
});

Example: Integrating with Freshdesk

The JSON Event can be used to integrate with Freshdesk as a Webhook rule in the Dispatch’r. That means events in Freshdesk can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey.

1. In Qualtrics, set your Event to JSON Event.
   
2. Copy the URL.
   
3. In a new tab, log into Freshdesk.
4. In the Admin section, navigate to the option that best fits the kind of rule you want to set.
   
   Qtip: Learn the difference between the Dispatch’r, Supervisor, and Observer on Freshdesk’s support documentation.
5. Create a new rule.
   
6. Set conditions to determine what Freshdesk event should trigger a task in Qualtrics.
   
   Example: Maybe when a Freshdesk Agent makes it so the ticket’s status is changed from any status to Resolved, you’d like to send a CSAT survey using Qualtrics.
7. Add a new action and select Trigger Web Hook.
   
8. Set the Request Type to POST.
   
9. In Callback URL, paste the JSON Event URL from Step 2.
10. To use token authentication, add custom headers, enter X-API-TOKEN: and set it equal to your API token.
    
11. To use HTTP Basic authentication, click Requires Authentication, add your Qualtrics username, and then instead of your password, enter your API token.
    
12. Make sure the Encoding is JSON.
    
13. Manually select content to pass over, or choose Advanced to enter a JSON body.
14. Save your rule.
15. In Qualtrics, finish your workflow. In this example, we would probably add an XM Directory Task.
    
16. Don’t forget to publish your survey changes when you’re ready to launch.

Example: Integrating with ServiceNow

The JSON Event can be used to integrate with ServiceNow. That means events in ServiceNow can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey.

1. In Qualtrics, set your Event to JSON Event.
   
2. Copy the URL.
   
3. In a new tab, log into your ServiceNow developer instance.
4. Select REST Message.
   
5. Click New.
6. Name your rest message.
   
7. In the Endpoint field, paste the URL you copied in Step 2.
8. Change Authentication type to Basic.
9. Go to the HTTP Request tab.
   
10. Double click to add X-API-TOKEN.
11. Double click to paste your API token.
    
12. In a new row, add the name Content-type.
13. Set the value to application/json.
14. Click Submit.
    
15. Reopen your Rest Message.
    
16. Under HTTP Methods, click New.
    
17. Give the method a name.
    
18. Set the HTTP Method to POST.
19. Set the Authentication type to Inherit from parent.
20. Click Submit.
21. Reopen the POST HTTP method you just created.
    
22. At the bottom of the page, select Preview Script Usage.
    
23. Copy the text.
24. Search and select Business Rules.
    
25. Select New.
26. Select a table.
    
27. Select Advanced.
28. Determine when the business rule is run.
    Example: If you have selected Incident for your table, and want to send a CSAT survey for resolved tickets, you could add a condition stating this rule should run when Incident state changes to Resolved.
    Qtip: Qualtrics Support can help you set up your JSON Event and connect it through ServiceNow. However, there might be some questions about ServiceNow functionality they cannot answer. If you have questions about how / when business rules run, please see ServiceNow’s documentation on how business rules work.
29. Go to the Advanced tab.
    
30. Paste the content you copied from Step 22 where it says Add your code here.
    
31. Add a body. This is where you communicate the information you’d like to pass over to Qualtrics.
    

    Example: This is an example of the final code you would include in this field. Most of this code is the outbound message provided by ServiceNow and will vary from example to example. Unfortunately, Qualtrics Support cannot help you with any custom coding; if you have issues with your code, please reach out to ServiceNow’s community for assistance.

    The bolded part of the code includes three additional functions not included in the original code: a JSON body that pulls the User ID and incident state, and a call that retrieves the email address of the incident customer so they can be sent the CSAT (italicized below). See ServiceNow’s documentation and consult their community if you have additional questions.

    (function executeRule(current, previous /*null when async*/) {
    
        // Add your code here
        
     try { 
         var r = new sn_ws.RESTMessageV2('Qualtrics JSON Event ', 'JSON Event POST');
         var body = {
             "User ID": gs.getUserID()
             "incident state": current.state.getDisplayValue()
         };
         
         var target = new GlideRecord('sys_user');
         target.addQuery('sys_id', '=', current.caller_id);
         target.query(); 
         while(target.next()) { 
             body["email"] = target.email.getDisplayValue();
         }      
          var response = r.execute();
         var responseBody = response.getBody();
         var httpStatus = response.getStatusCode();
         gs.addInfoMessage(httpStatus);
        }
    catch(ex) {
         var message = ex.message;
         gs.addInfoMessage("Error communicating w Qualtrics " + message);
    
    }
    
    })(current, previous);

32. Add the body to the request. Add the following under the bolded, italicized portion of the code from the previous step:

     r.setRequestBody(JSON.stringify(body)); 

33. Click Submit.
34. In Qualtrics, finish your workflow. To continue the CSAT survey example, we would probably add a XM Directory Task.
    
35. Don’t forget to publish your survey changes when you’re ready to launch.

Example: Integrating with Microsoft Dynamics Through Microsoft Flow

The JSON Event makes it so events in Microsoft Dynamics can then trigger tasks in Qualtrics, such as the creation of a ticket, or the distribution of a survey. For example, whenever you delete an account record in Microsoft, you can distribute a Qualtrics survey to the account owner that asks exit questions. (e.g., We’re sorry to see you go! How was your time with us? How can we improve?)

In order to integrate the JSON Event with actions that occur in Microsoft Dynamics, you actually need to do the set up inside Microsoft Flow instead of Dynamics. Don’t worry – Microsoft Flow comes free with every Microsoft Dynamics account, so you can log into Flow with your Dynamics information here.

1. In Qualtrics, set your Event to JSON Event.
   
2. Copy the URL.
   
3. In a separate tab, go to https://us.flow.microsoft.com/en-us/ and use your Microsoft Dynamics information to log into Flow.
4. Select My Flows on the left.
   
5. Click New and select Automated – from blank.
6. Name the flow.
   
7. Select a trigger. This is the event that happens in Microsoft that will start the task in Qualtrics. You can choose whatever serves your purposes, but for this example, we would choose “When a record is deleted (Dynamics 365).”
8. Click Create.
9. Under Organization Name, log into your Dynamics account.
   
10. Under Entity Name, choose the type of record or file. For our example, we’d use “Accounts.”
11. Click Next Step, and select Add an Action.
12. Select HTTP.
    
13. Change the Method to POST.
14. Paste your JSON Event URL in the URI field.
15. Use token authentication. Under Headers, enter X-API-TOKEN and in the field next to it, paste your API token.
16. Under Body, you can enter a JSON body. This helps you decide the information you want to pass from Dynamics to Qualtrics.
    Qtip: Use the Add dynamic content button to select Dynamics record fields you’d like to bring over to Qualtrics. Make sure you follow proper JSON format, as displayed in the screenshot. For help troubleshooting dynamic content, please reach out to Microsoft Support.
17. When you’re finished, click Save.
18. In Qualtrics, finish your workflow. In this example, we would probably add an XM Directory Task.
    
19. Don’t forget to publish your survey changes when you’re ready to launch.

Example: Integrating with Genesys PureCloud

Using JSON events, you can integrate with Genesys PureCloud to send customers a follow-up survey after completing a support phone or chat interaction.

1. In the survey you want to send, navigate to Workflows.
   
2. Create a new event-based workflow.
3. For the workflow event, select the JSON event.
   
4. Click Copy URL to copy the event endpoint to your clipboard.
   
5. Without closing out of the JSON Event window, open a new tab in your browser and navigate to Genesys.
6. Navigate to Admin.
   
7. Click Actions.
8. Click Add Action.
   
9. Select Web Services Data Actions as the Integration Name.
   
   Qtip: If you don’t have the option to select the Web Services Data Actions, then you need to enable the integration. See this page for more information.
10. Give your action an Action Name.
11. Click Add.
12. Navigate to the Setup tab.
    
13. Go to the Contracts tab.
14. Under Input Contract, select JSON.
15. Configure the properties that are sent to Qualtrics.

    Example: For example, the below code will pass email address, phone number, first name, and last name.

    {
           "type": "object",
           "properties": {
             "emailAddress": {
               "type": "string"
             },
             "phoneNumber": {
               "type": "string"
             },
             "firstName": {
               "type": "string"
             },
             "lastName": {
               "type": "string"
             }
           },
           "additionalProperties": true
         }

16. Go to the Configuration tab.
17. Change the Request type to POST.
18. In the Request URL Template field, paste the URL from the JSON Event in Qualtrics.
19. Click Add Header.
    
20. In the Key box, enter X-API-TOKEN.
21. In the Value box, enter your Qualtrics API token.
22. Go to the Test tab.
23. Enter test values for your properties.
24. Click Run Action.
25. Genesys will tell you if the action was successful. If it failed, the error response will be displayed to help you fix the issue.
    
26. Return to your JSON Event in Qualtrics and check that your properties were passed to Qualtrics successfully.
27. Click Save.
28. Click the plus sign ( + ) and then Task to set up the task you want to follow when the JSON event is triggered. In our case, we want to send a survey to respondents, so we select the XM Directory Task.
    Qtip: When setting up your task, use the piped text menu to use values passed from Genesys (e.g., customer email, name, etc).
29. After setting up the task in Qualtrics, return to Genesys and click Save & Publish.
    
30. Click Yes.
31. Navigate to Admin.
32. Click Architect.
33. Select Survey Invite in the flow dropdown menu.
34. Click Add.
35. Give your flow a Name, Description, and Division.
36. Click Create Flow.
37. Under the Data section in your Toolbox, select Call Data Action and drag it to the dropbox in the flow.
38. Give your action a Name.
39. For the Category, select Web Services Data Action.
40. For Data Action, select the data action you created earlier.
41. Next to each property, click the dropdown menu and select Expression.
42. For the property values, enter what data is being sent for each property. The box will autocomplete your fields as you type.
    Qtip: This page has every default property included in the survey invite flow. You can also use complex expressions in situations where customer contact information is missing or requires additional formatting.
    Qtip: Contact information is prefaced with Survey.CustomerContact.
43. Click the bottom-most box in your flow.
44. Select Toolbox, then Survey Invites, then Abort Survey.
45. Select optOut for the Disposition.
46. Click Publish. Genesys will validate the flow and then publish it. Once this is done, the flow is in place and will begin sending surveys to customers when they complete support interactions.

FAQs